Best Practices

Good API documentation

Good API documentation allows any developer considering the API to quickly understand the purpose of the API, the data it works with, and how to send requests and parse the responses. Some documentation, particularly for large projects, even host samples you can run within the documentation to see the API in action. For the purposes of this course, you don't need to implement interactivity, but you will provide examples that can be run by someone viewing your documentation.

Here's a recap (for your reference) of the components that are typically included in good API documentation:

• Introduction
• Getting Started
  • Base URL
  • API Keys /Authentication (if applicable)
• Errors
  • Response codes
  • Messages
  • Error types
• Resource endpoint library
  • Organized by resource
  • Include each endpoint
  • Sample request
  • Arguments including data types
  • Response object including status codes and data types